Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 4 - Unicode Converter Reference / Unicode Converter Functions

Truncating Strings Before Converting Them /

TruncateForTextToUnicode

Identifies where your application can safely break a multibyte string to be converted to Unicode so that the string is not broken in the middle of a multibyte character.

pascal OSStatus TruncateForTextToUnicode(
      ConstTextToUnicodeInfo iTextToUnicodeInfo,
      ByteCount iSourceLen, 
      ConstLogicalAddress iSourceStr, 
      ByteCount iMaxLen, 
      ByteCount *oTruncatedLen);

iTextToUnicodeInfo

The Unicode converter object of type TextToUnicodeInfo (page 119) for the text string to be divided up with each segment properly truncated. The TruncateForTextToUnicode function does not modify the object's contents.

iSourceLen

The length in bytes of the multibyte string to be divided up.

iSourceStr

The address of the multibyte string to be divided up.

iMaxLen

The maximum allowable length of the string to be truncated. This must be less than or equal to iSourceLen.

oTruncatedLen

A pointer to a value of type ByteCount. On output, this value contains the length of the longest portion of the multibyte string, pointed to by iSourceStr, that is less than or equal to the length specified by iMaxLen. This identifies the byte after which you can break the string.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) in the chapter "Basic Text Types Reference."

DISCUSSION

Your application can use this function to break a string properly before you call the function ConvertFromTextToUnicode (page 129) so that the string you pass it is terminated with complete characters. You can call this function repeatedly to properly divide up a text segment, each time identifying the new beginning of the string, until the last portion of the text is less than or equal to the maximum allowable length. Each time you use the function, you get a properly terminated string within the allowable length range. You use the function as many times as necessary to be able to convert the entire text segment.

Because the TruncateForTextToUnicode function does not modify the contents of the Unicode converter object, you can call this function safely between calls to the function ConvertFromTextToUnicode (page 129).

If the function returns paramErr, kTECGlobalsUnavailableErr, or kTECTableFormatErr the value returned by the oTruncatedLen parameter is invalid.